Jetfire Code: Hints for Writing Good Code

Modified on 2009/12/07 02:04 by Charles Categorized as Jetfire Code, Jetfire Language
{toc}

===Jetfire Code: Hints for Writing Good Code===

This page contains a number of suggestions that may help in writing good Jetfire code.  The suggestions include: 
* Structure Hints
* Syntax Hints
* Semantic Hints

====Structure Hints====

* Keep the size of the code files small.

* Follow indentation practices to make your code easy to read.  Whitespace makes code easier to read.

* Follow the code template.  TrackerRealm marks Jetfire code as GNU GPL.  Decide how you copyright your code and add it to the top of the code file.

{{{{
// TheNameOfTheWorkflow    W O R K F L O W
//===================================================================================
// TheNameOfTheFile.txt
//===================================================================================
// Copyright (C) 2009 TrackerRealm Corporation
// This file is part of Jetfire.  http://Jetfire.ca
// 
// Jetfire is open software: you can redistribute it and/or modify it under the terms of the 
// GNU General Public License as published by the Free Software Foundation, version 3 of the License.
// 
// Jetfire is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
// without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
// See the GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License along with Jetfire.  
// If not, see http://www.gnu.org/licenses.
// REMOVAL OF THIS NOTICE IS VIOLATION OF THE COPYRIGHT.
//===================================================================================
// DisplayName: 'Friendly name for the class'
// This code does the following:
// * List of features 

namespace TheNamespace
{
	// This workflow provides a Base Class for associating Questions and Answers.
	public workflow TheNameOfTheWorkflow
	{
	}
}
}}}}

* The namespace and workflow class name forms a unique name that identifies the code that you write. e.g. the namespace, JetfireApps is used for the Jetfire code applications written by TrackerRealm.  You do not need to have a separate namespace for every Jetfire code class.  Pick a namespace that is meaningful and memorable.

* The namespace and workflow class name forms a unique name that identifies the code that you write.  e.g. pick a workflow class name that is meaningful and succinct.

* Workflows can contain other workflows to build complex relationships.  When adding a child workflow to the parent workflow, 'return the workflow' to the calling method.

{{{{
   // A list property in the parent workflow.
   public List WorkflowList
   {
      get;
      private set;
   }
   // Create a workflow and return it to the calling method.
   public MyWorkflow AddMyWorkflow()
   {
      // Create a workflow.
      MyWorkflow w = new MyWorkflow();
      // the new workflow is added to a list in the parent workflow to create a reference.
      WorkflowList.Add(w);
      // the new workflow is returned so that the calling method can use it directly.
      return w;
   }
}}}}

====Syntax Hints====

* Add Comments to your code.
** No matter how small the code foot-print is, people forget what code does after a certain time.

* Use the C# 3.0 syntax for writing properties

{{{{
   // SomeProperty stores something.
   // Note that this property can be read and written by anyone.
   public string SomeProperty
   {
      get;
      set;
   }
}}}}

* Keep states and access in the same order.  This makes it easy to read and compare properties and methods in the workflow.

{{{{
   // SomeProperty stores something.
   // The states access modifier is added before the access access modifier.
   public string SomeProperty : states(SomeState), access("SomeRole")
   {
      get;
      set;
   }
}}}}

====Semantic Hints====

* Last time updated
** Some workflows require that a timestamp be updated in the workflow every time that the workflow is updated.  This can easily be done by adding a 'LastUpdated' property to the workflow and updating it in the Save Method.

{{{{
   // Store the Last time that the workflow was updated.
   // Note the use of the private access modifier.  This property can only be set from within the workflow
   public DateTime LastUpdated
   {
      get;
      private set;
   }
}}}}

* Save Methods
** There are a number of situations where a Jetfire Save Method is called when data is saved to a workflow in a Jetfire Web Part.  e.g. 
*** Jetfire code can be used to validate whether the user has added all of the necessary properties.  
*** Updating a Last Update timestamp.
** Create a save method that is added to the Jetfire Web Part (the Edit Property of the Web Part is called 'Save Method'.)

{{{{
   // Add the name of this method to the 'Save Method' Edit Property of the Jetfire Web Part.
   public void FinishEdit()
   {
      // Update the Last time that the workflow was saved when the Workflow is saved.
      LastUpdate = DateTime.Now;
   }
}}}}

{{{{
   // Check if the first and last variables are blank when the workflow is saved.
   public void FinishEdit()
   {
      if (first == "")
         throw exception("Enter First Name");
      if (last == "")
         throw exception("Enter Last Name");
   }
}}}}

* Use throw exception in Jetfire Code to identify an error.
** When throw exception is encountered in Jetfire Code, an error is generated and appears in the Jetfire Web Part as a message.  In the above code "Enter First Name" is displayed to the user when the first name is not input on the Web Form.

* Naming States and Methods 
** States and Methods can be confusing when combined in a workflow because they look similar.  Here are a couple of conventions that you can use to reduce the confusion.
*** The state name is 'Delete'.  Methods that promote the state to Delete are prefixed with 'Promote_To_'.
*** Use past tense for state names, e.g. 'Deleted'.  Use present tense for methods, e.g. 'Delete'.

Convention a) prefix methods with 'Promote_to_'
{{{{
   public Delete() { }
   public void Promote_to_Delete()
   {
      enterstate Delete();
   }
}}}}

Convention b) use present tense for methods
{{{{
   public Deleted() { }
   public void Delete()
   {
      enterstate Deleted();
   }
}}}}

* Only Logged in users can set a property
** Jetfire code supports dynamic access modifiers.  This means that the Workflow Designer can identify who can set or get properties and execute methods.  A typical requirement is that a property be set by anyone EXCEPT Guests.
** The following pattern is used to prevent Guests from setting the property.
** The 'IsNotGuest' method can be used as an expression in the access evaluation or as a regular method called from other Jetfire Methods.

{{{{
   public string MyFavoriteProperty
   {
	get;
	set : access(IsNotGuest);
   }
   public bool IsNotGuest()
   {
        return User.Login.Name != "Guest";
   }
}}}}
Meta Keywords:
Meta Description:
Change Comment: